IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/perl5/CGI::Cookie.z/CGI::Cookie

Text File | 2002-10-03 | 12.3 KB | 331 lines

CCCCGGGGIIII::::::::CCCCooooooookkkkiiiieeee((((3333))))                                                  CCCCGGGGIIII::::::::CCCCooooooookkkkiiiieeee((((3333))))



NNNNAAAAMMMMEEEE
     CGI::Cookie - Interface to Netscape Cookies

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
         use CGI qw/:standard/;
         use CGI::Cookie;

         # Create new cookies and send them
         $cookie1 = new CGI::Cookie(-name=>'ID',-value=>123456);
         $cookie2 = new CGI::Cookie(-name=>'preferences',
                                    -value=>{ font => Helvetica,
                                              size => 12 }
                                    );
         print header(-cookie=>[$cookie1,$cookie2]);

         # fetch existing cookies
         %cookies = fetch CGI::Cookie;
         $id = $cookies{'ID'}->value;

         # create cookies returned from an external source
         %cookies = parse CGI::Cookie($ENV{COOKIE});


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     CGI::Cookie is an interface to Netscape (HTTP/1.1) cookies, an innovation
     that allows Web servers to store persistent information on the browser's
     side of the connection.  Although CGI::Cookie is intended to be used in
     conjunction with CGI.pm (and is in fact used by it internally), you can
     use this module independently.

     For full information on cookies see

             http://www.ics.uci.edu/pub/ietf/http/rfc2109.txt


UUUUSSSSIIIINNNNGGGG CCCCGGGGIIII::::::::CCCCooooooookkkkiiiieeee
     CGI::Cookie is object oriented.  Each cookie object has a name and a
     value.  The name is any scalar value.  The value is any scalar or array
     value (associative arrays are also allowed).  Cookies also have several
     optional attributes, including:

     1111.... eeeexxxxppppiiiirrrraaaattttiiiioooonnnn ddddaaaatttteeee
         The expiration date tells the browser how long to hang on to the
         cookie.  If the cookie specifies an expiration date in the future,
         the browser will store the cookie information in a disk file and
         return it to the server every time the user reconnects (until the
         expiration date is reached).  If the cookie species an expiration
         date in the past, the browser will remove the cookie from the disk
         file.  If the expiration date is not specified, the cookie will
         persist only until the user quits the browser.





                                                                        PPPPaaaaggggeeee 1111






CCCCGGGGIIII::::::::CCCCooooooookkkkiiiieeee((((3333))))                                                  CCCCGGGGIIII::::::::CCCCooooooookkkkiiiieeee((((3333))))



     2222.... ddddoooommmmaaaaiiiinnnn
         This is a partial or complete domain name for which the cookie is
         valid.  The browser will return the cookie to any host that matches
         the partial domain name.  For example, if you specify a domain name
         of ".capricorn.com", then Netscape will return the cookie to Web
         servers running on any of the machines "www.capricorn.com",
         "ftp.capricorn.com", "feckless.capricorn.com", etc.  Domain names
         must contain at least two periods to prevent attempts to match on top
         level domains like ".edu".  If no domain is specified, then the
         browser will only return the cookie to servers on the host the cookie
         originated from.

     3333.... ppppaaaatttthhhh
         If you provide a cookie path attribute, the browser will check it
         against your script's URL before returning the cookie.  For example,
         if you specify the path "/cgi-bin", then the cookie will be returned
         to each of the scripts "/cgi-bin/tally.pl", "/cgi-bin/order.pl", and
         "/cgi-bin/customer_service/complain.pl", but not to the script
         "/cgi-private/site_admin.pl".  By default, path is set to "/", which
         causes the cookie to be sent to any CGI script on your site.

     4444.... sssseeeeccccuuuurrrreeee ffffllllaaaagggg
         If the "secure" attribute is set, the cookie will only be sent to
         your script if the CGI request is occurring on a secure channel, such
         as SSL.

     CCCCrrrreeeeaaaattttiiiinnnngggg NNNNeeeewwww CCCCooooooookkkkiiiieeeessss

             $c = new CGI::Cookie(-name    =>  'foo',
                                  -value   =>  'bar',
                                  -expires =>  '+3M',
                                  -domain  =>  '.capricorn.com',
                                  -path    =>  '/cgi-bin/database'
                                  -secure  =>  1
                                 );

     Create cookies from scratch with the nnnneeeewwww method.  The ----nnnnaaaammmmeeee and ----vvvvaaaalllluuuueeee
     parameters are required.  The name must be a scalar value.  The value can
     be a scalar, an array reference, or a hash reference.  (At some point in
     the future cookies will support one of the Perl object serialization
     protocols for full generality).

     ----eeeexxxxppppiiiirrrreeeessss accepts any of the relative or absolute date formats recognized
     by CGI.pm, for example "+3M" for three months in the future.  See
     CGI.pm's documentation for details.

     ----ddddoooommmmaaaaiiiinnnn points to a domain name or to a fully qualified host name.  If
     not specified, the cookie will be returned only to the Web server that
     created it.






                                                                        PPPPaaaaggggeeee 2222






CCCCGGGGIIII::::::::CCCCooooooookkkkiiiieeee((((3333))))                                                  CCCCGGGGIIII::::::::CCCCooooooookkkkiiiieeee((((3333))))



     ----ppppaaaatttthhhh points to a partial URL on the current server.  The cookie will be
     returned to all URLs beginning with the specified path.  If not
     specified, it defaults to '/', which returns the cookie to all pages at
     your site.

     ----sssseeeeccccuuuurrrreeee if set to a true value instructs the browser to return the cookie
     only when a cryptographic protocol is in use.

     SSSSeeeennnnddddiiiinnnngggg tttthhhheeee CCCCooooooookkkkiiiieeee ttttoooo tttthhhheeee BBBBrrrroooowwwwsssseeeerrrr

     Within a CGI script you can send a cookie to the browser by creating one
     or more Set-Cookie: fields in the HTTP header.  Here is a typical
     sequence:

       my $c = new CGI::Cookie(-name    =>  'foo',
                               -value   =>  ['bar','baz'],
                               -expires =>  '+3M');

       print "Set-Cookie: $c\n";
       print "Content-Type: text/html\n\n";

     To send more than one cookie, create several Set-Cookie: fields.
     Alternatively, you may concatenate the cookies together with "; " and
     send them in one field.

     If you are using CGI.pm, you send cookies by providing a -cookie argument
     to the _h_e_a_d_e_r() method:

       print header(-cookie=>$c);

     Mod_perl users can set cookies using the request object's _h_e_a_d_e_r__o_u_t()
     method:

       $r->header_out('Set-Cookie',$c);

     Internally, Cookie overloads the "" operator to call its _a_s__s_t_r_i_n_g()
     method when incorporated into the HTTP header.  _a_s__s_t_r_i_n_g() turns the
     Cookie's internal representation into an RFC-compliant text
     representation.  You may call _a_s__s_t_r_i_n_g() yourself if you prefer:

       print "Set-Cookie: ",$c->as_string,"\n";


     RRRReeeeccccoooovvvveeeerrrriiiinnnngggg PPPPrrrreeeevvvviiiioooouuuussss CCCCooooooookkkkiiiieeeessss

             %cookies = fetch CGI::Cookie;

     ffffeeeettttcccchhhh returns an associative array consisting of all cookies returned by
     the browser.  The keys of the array are the cookie names.  You can
     iterate through the cookies this way:





                                                                        PPPPaaaaggggeeee 3333






CCCCGGGGIIII::::::::CCCCooooooookkkkiiiieeee((((3333))))                                                  CCCCGGGGIIII::::::::CCCCooooooookkkkiiiieeee((((3333))))



             %cookies = fetch CGI::Cookie;
             foreach (keys %cookies) {
                do_something($cookies{$_});
             }

     In a scalar context, _f_e_t_c_h() returns a hash reference, which may be more
     efficient if you are manipulating multiple cookies.

     CGI.pm uses the URL escaping methods to save and restore reserved
     characters in its cookies.  If you are trying to retrieve a cookie set by
     a foreign server, this escaping method may trip you up.  Use _r_a_w__f_e_t_c_h()
     instead, which has the same semantics as _f_e_t_c_h(), but performs no
     unescaping.

     You may also retrieve cookies that were stored in some external form
     using the _p_a_r_s_e() class method:

            $COOKIES = `cat /usr/tmp/Cookie_stash`;
            %cookies = parse CGI::Cookie($COOKIES);


     MMMMaaaannnniiiippppuuuullllaaaattttiiiinnnngggg CCCCooooooookkkkiiiieeeessss

     Cookie objects have a series of accessor methods to get and set cookie
     attributes.  Each accessor has a similar syntax.  Called without
     arguments, the accessor returns the current value of the attribute.
     Called with an argument, the accessor changes the attribute and returns
     its new value.

     nnnnaaaammmmeeee(((())))
         Get or set the cookie's name.  Example:

                 $name = $c->name;
                 $new_name = $c->name('fred');


     vvvvaaaalllluuuueeee(((())))
         Get or set the cookie's value.  Example:

                 $value = $c->value;
                 @new_value = $c->value(['a','b','c','d']);

         vvvvaaaalllluuuueeee(((()))) is context sensitive.  In an array context it will return the
         current value of the cookie as an array.  In a scalar context it will
         return the ffffiiiirrrrsssstttt value of a multivalued cookie.

     ddddoooommmmaaaaiiiinnnn(((())))
         Get or set the cookie's domain.

     ppppaaaatttthhhh(((())))
         Get or set the cookie's path.




                                                                        PPPPaaaaggggeeee 4444






CCCCGGGGIIII::::::::CCCCooooooookkkkiiiieeee((((3333))))                                                  CCCCGGGGIIII::::::::CCCCooooooookkkkiiiieeee((((3333))))



     eeeexxxxppppiiiirrrreeeessss(((())))
         Get or set the cookie's expiration time.

AAAAUUUUTTTTHHHHOOOORRRR IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN
     be used and modified freely, but I do request that this copyright notice
     remain attached to the file.  You may modify this module as you wish, but
     if you redistribute a modified version, please attach a note listing the
     modifications you have made.

     Address bug reports and comments to:  [e-mail]

BBBBUUUUGGGGSSSS
     This section intentionally left blank.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     the _C_G_I::_C_a_r_p manpage, the _C_G_I manpage

     =cut





































                                                                        PPPPaaaaggggeeee 5555